home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_perl.idb / usr / freeware / catman / p_man / cat3 / AutoLoader.Z / AutoLoader
Encoding:
Text File  |  1998-10-28  |  10.4 KB  |  265 lines
  1.  
  2.  
  3.  
  4.      AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr((((3333))))   22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))     AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr((((3333))))
  5.  
  6.  
  7.  
  8.      NNNNAAAAMMMMEEEE
  9.       AutoLoader - load subroutines    only on    demand
  10.  
  11.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.           package Foo;
  13.           use AutoLoader 'AUTOLOAD';   # import the    default    AUTOLOAD subroutine
  14.  
  15.           package Bar;
  16.           use AutoLoader;           # don't import AUTOLOAD, define our own
  17.           sub AUTOLOAD {
  18.           ...
  19.           $AutoLoader::AUTOLOAD    = "...";
  20.           goto &AutoLoader::AUTOLOAD;
  21.           }
  22.  
  23.  
  24.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  25.       The AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr module    works with the AAAAuuuuttttooooSSSSpppplllliiiitttt module    and
  26.       the __END__ token to defer the loading of some subroutines
  27.       until    they are used rather than loading them all at once.
  28.  
  29.       To use AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr, the author    of a module has    to place the
  30.       definitions of subroutines to    be autoloaded after an __END__
  31.       token.  (See the _p_e_r_l_d_a_t_a manpage.)  The AAAAuuuuttttooooSSSSpppplllliiiitttt module
  32.       can then be run manually to extract the definitions into
  33.       individual files _a_u_t_o/_f_u_n_c_n_a_m_e._a_l.
  34.  
  35.       AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr implements    an AUTOLOAD subroutine.     When an
  36.       undefined subroutine in is called in a client    module of
  37.       AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr, AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr's AUTOLOAD subroutine attempts    to
  38.       locate the subroutine    in a file with a name related to the
  39.       location of the file from which the client module was    read.
  40.       As an    example, if _P_O_S_I_X._p_m is    located    in
  41.       /_u_s_r/_l_o_c_a_l/_l_i_b/_p_e_r_l_5/_P_O_S_I_X._p_m, AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr will look for perl
  42.       subroutines PPPPOOOOSSSSIIIIXXXX in /_u_s_r/_l_o_c_a_l/_l_i_b/_p_e_r_l_5/_a_u_t_o/_P_O_S_I_X/*._a_l,
  43.       where    the .al    file has the same name as the subroutine, sans
  44.       package.  If such a file exists, AUTOLOAD will read and
  45.       evaluate it, thus (presumably) defining the needed
  46.       subroutine.  AUTOLOAD    will then goto the newly defined
  47.       subroutine.
  48.  
  49.       Once this process completes for a given funtion, it is
  50.       defined, so future calls to the subroutine will bypass the
  51.       AUTOLOAD mechanism.
  52.  
  53.       SSSSuuuubbbbrrrroooouuuuttttiiiinnnneeee SSSSttttuuuubbbbssss
  54.  
  55.       In order for object method lookup and/or prototype checking
  56.       to operate correctly even when methods have not yet been
  57.       defined it is    necessary to "forward declare" each subroutine
  58.       (as in sub NAME;).  See the section on _S_Y_N_O_P_S_I_S in the
  59.       _p_e_r_l_s_u_b manpage.  Such forward declaration creates
  60.  
  61.  
  62.  
  63.      Page 1                        (printed 10/23/98)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr((((3333))))   22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))     AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr((((3333))))
  71.  
  72.  
  73.  
  74.       "subroutine stubs", which are    place holders with no code.
  75.  
  76.       The AutoSplit    and AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr modules automate    the creation
  77.       of forward declarations.  The    AutoSplit module creates an
  78.       'index' file containing forward declarations of all the
  79.       AutoSplit subroutines.  When the AutoLoader module is    'use'd
  80.       it loads these declarations into its callers package.
  81.  
  82.       Because of this mechanism it is important that AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr is
  83.       always used and not required.
  84.  
  85.       UUUUssssiiiinnnngggg    AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr's AUTOLOAD Subroutine
  86.  
  87.       In order to use AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr's AUTOLOAD    subroutine you _m_u_s_t
  88.       explicitly import it:
  89.  
  90.           use AutoLoader 'AUTOLOAD';
  91.  
  92.  
  93.       OOOOvvvveeeerrrrrrrriiiiddddiiiinnnngggg AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr's AUTOLOAD Subroutine
  94.  
  95.       Some modules,    mainly extensions, provide their own AUTOLOAD
  96.       subroutines.    They typically need to check for some special
  97.       cases    (such as constants) and    then fallback to AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr's
  98.       AUTOLOAD for the rest.
  99.  
  100.       Such modules should _n_o_t import AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr's AUTOLOAD
  101.       subroutine.  Instead,    they should define their own AUTOLOAD
  102.       subroutines along these lines:
  103.  
  104.           use AutoLoader;
  105.           use Carp;
  106.  
  107.           sub AUTOLOAD {
  108.           my $constname;
  109.           ($constname =    $AUTOLOAD) =~ s/.*:://;
  110.           my $val = constant($constname, @_ ? $_[0] : 0);
  111.           if ($! != 0) {
  112.               if ($! =~    /Invalid/) {
  113.               $AutoLoader::AUTOLOAD    = $AUTOLOAD;
  114.               goto &AutoLoader::AUTOLOAD;
  115.               }
  116.               else {
  117.               croak    "Your vendor has not defined constant $constname";
  118.               }
  119.           }
  120.           *$AUTOLOAD = sub { $val }; # same as:    eval "sub $AUTOLOAD { $val }";
  121.           goto &$AUTOLOAD;
  122.           }
  123.  
  124.       If any module's own AUTOLOAD subroutine has no need to
  125.       fallback to the AutoLoader's AUTOLOAD    subroutine (because it
  126.  
  127.  
  128.  
  129.      Page 2                        (printed 10/23/98)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr((((3333))))   22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))     AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr((((3333))))
  137.  
  138.  
  139.  
  140.       doesn't have any AutoSplit subroutines), then    that module
  141.       should not use AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr at all.
  142.  
  143.       PPPPaaaacccckkkkaaaaggggeeee LLLLeeeexxxxiiiiccccaaaallllssss
  144.  
  145.       Package lexicals declared with my in the main    block of a
  146.       package using    AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr will    not be visible to auto-loaded
  147.       subroutines, due to the fact that the    given scope ends at
  148.       the __END__ marker.  A module    using such variables as
  149.       package globals will not work    properly under the AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr.
  150.  
  151.       The vars pragma (see the section on _v_a_r_s in the _p_e_r_l_m_o_d
  152.       manpage) may be used in such situations as an    alternative to
  153.       explicitly qualifying    all globals with the package
  154.       namespace.  Variables    pre-declared with this pragma will be
  155.       visible to any autoloaded routines (but will not be
  156.       invisible outside the    package, unfortunately).
  157.  
  158.       AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr vs. SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr
  159.  
  160.       The AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr is similar in purpose to SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr: both
  161.       delay    the loading of subroutines.
  162.  
  163.       SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr uses the __DATA__ marker rather than __END__.
  164.       While    this avoids the    use of a hierarchy of disk files and
  165.       the associated open/close for    each routine loaded,
  166.       SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr suffers a startup speed disadvantage in the one-
  167.       time parsing of the lines after __DATA__, after which
  168.       routines are cached.    SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr can also handle multiple
  169.       packages in a    file.
  170.  
  171.       AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr only reads    code as    it is requested, and in    many
  172.       cases    should be faster, but requires a machanism like
  173.       AAAAuuuuttttooooSSSSpppplllliiiitttt be used to create the individual files.  the
  174.       _E_x_t_U_t_i_l_s::_M_a_k_e_M_a_k_e_r manpage will invoke AAAAuuuuttttooooSSSSpppplllliiiitttt
  175.       automatically    if AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr is used in a module source file.
  176.  
  177.      CCCCAAAAVVVVEEEEAAAATTTTSSSS
  178.       AutoLoaders prior to Perl 5.002 had a    slightly different
  179.       interface.  Any old modules which use    AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr should be
  180.       changed to the new calling style.  Typically this just means
  181.       changing a require to    a use, adding the explicit 'AUTOLOAD'
  182.       import if needed, and    removing AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr from @ISA.
  183.  
  184.       On systems with restrictions on file name length, the    file
  185.       corresponding    to a subroutine    may have a shorter name    that
  186.       the routine itself.  This can    lead to    conflicting file
  187.       names.  The _A_u_t_o_S_p_l_i_t    package    warns of these potential
  188.       conflicts when used to split a module.
  189.  
  190.       AutoLoader may fail to find the autosplit files (or even
  191.       find the wrong ones) in cases    where @INC contains relative
  192.  
  193.  
  194.  
  195.      Page 3                        (printed 10/23/98)
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.      AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr((((3333))))   22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))     AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr((((3333))))
  203.  
  204.  
  205.  
  206.       paths, aaaannnndddd the program does chdir.
  207.  
  208.      SSSSEEEEEEEE AAAALLLLSSSSOOOO
  209.       the _S_e_l_f_L_o_a_d_e_r manpage - an autoloader that doesn't use
  210.       external files.
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.      Page 4                        (printed 10/23/98)
  262.  
  263.  
  264.  
  265.